Here are some classes which I use to provide Balloon Help for my PowerPlant based application. This provides balloon help for individual panes in windows or dialogs. This is an update from an early version of these classes and provides a number of new useful features:
(1) Balloon help can now be obtained in LDialogBox sub-classes.
(2) Balloon help is now available for disabled items.
(3) Balloon help can be context sensitive with different text for enabled or disabled panes and controls which are on or off.
(4) Constructor custom types are now available for adding balloon help in Constructor rather than writing any code.
(5) Performance improved - previously there was a delay when moving the cursor over an item with balloon help. Now the balloon appears much faster and copes better with the cursor being moved around quickly.
Basic principal
The ‘AdjustCursor’ method of the LApplication and StDialogHandler classes is overridden to provide additional functionality. Now, whenever the cursor moves over a new pane, the ‘ExecuteAttachments’ method for the new pane is called with the message ‘msg_ShowHelp’. If the pane has a ‘CHelpAttach’ attachment and balloon help is on then a balloon is produced for that pane. The code takes care of tracking the current ‘help target pane’ and removing the balloon when the cursor moves out of the pane. Also if the state of the pane or control changes while the balloon is over the pane then the balloon help text may change depending on the type of attachment in use.
Using the main classes
Add ‘CBalloonApp.cp’, ‘CBalloonDialog.cp’ and ‘CHelpAttach.cp’ to your project.
Derive your application class from ‘CBalloonApp’ (make sure that you do not override the AdjustCursor method in your application class, or if you do make sure you call the inherited method).
To use balloons in a ‘LDialogBox’ sub-class use the ‘CBalloonDialog’ class in place of ‘StDialogHandler’.
Using the attachments
There are now three help attachment classes:
CHelpAttach : provides a single ‘STR#’ index. The balloon is shown for enabled and disabled panes.
CHelpPaneAttach : provides two ‘STR#’ indexes. The first is used if the pane is enabled, the second is used if the pane is disabled.
CHelpControlAttach : provides three ‘STR#’ indexes. The first is used if the control is enabled and its value is not zero, the second is used if thecontrol is enabled and its value is zero, the third is used if the control is disabled and does not depend on the value. IMPORTANT This class must only be attached to sub-classes of ‘LControl’ as it type-casts its ioParam value to ‘LControl’. Failure to do this will almost certainly result in a crash.
There are two ways to use these attachments:
Add them programmatically :
Add a ‘CHelpAttach’ class or one of its sub-classes to each item in a window for which you want to provide balloon help. This is best done in the window’s ‘FinishCreateSelf’ method. When creating the ‘CHelpAttach’ you need to specify a ‘STR#’ resource id and the requisite number of indexes which are used to get the balloon's text.
The ‘HelpAttach.rsrc’ file contains three custom pane types for Constructor. To use these, copy them to your project’s Constructor file. The custom types will then appear in the ‘PowerPlant Display Classes’ list. To add a help attachment, use the ‘Show Hierarchy’ view and drag the appropriate attachment from the display list to the pane or control that requires a balloon. Then double-click the new attachment and set the STR# resource details (note that the ‘Execute Message’ value is irrelevant as the help attachments over ride this value to set the proper help message value).
At the moment one problem exists with this scheme - adding help to the default button in a dialog. The problem arises because the ‘LDialogBox’ class creates a ‘LDefaultOutline’ class which sits above the default button’s pane and is not accessible via Constructor. Thus the help attachment for the default button never gets executed as the default outline is the pane that is found in the ‘AdjustCursor’ methods. The only way round this is to programmatically add the help attachment to the default outline.
Notes
If you wish to customise your help balloons (ie provide pictures or styled text in the balloon) then sub-class the ‘CHelpAttach’ classes and override the ‘FillHMRecord’ method.
If you have any comments, find any bugs or come up with any improvements then please let me know. Feel free to use this code in whatever way you like.
